SpecialHost, a program to include IFF graphics in TEXtexts

for the AMIGA

β-Version 0.71

of 06. March 1995

by Georg Heßmann translation by Thomas Tavoly

Abstract

SpecialHost is a utility for the previewer ShowDVI and the printerdriver DVIprint. It is started in the background additionally to the drivers and waits for messages from these programs. It enables the printerdriver and the previewer to display IFF graphics. To this end it evaluates the \special-strings. It loads pictures with the help of an IFF library and adjusts their size to the resolution of the current driver. It can also store the pictures in a manner that when called again the labour intensive enlargement or reduction do not have to be done again.

Table of contents:

1. Copyright and similar . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3 2. About SpecialHost . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3 3. Calling SpecialHost . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4 4. SpecialHost’s window structure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4 5. Operating SpecialHost . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4 6. The format of the \special-string . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5 7. The software interface to the drivers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7

7.1. The communication through ports . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7 7.2. The bitmap-file format . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7 7.3. The Source . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8

8. To Do . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8 9. Hard- and software required . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9 10. Known bugs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9

1. Copyright and similar

The program SpecialHost is “freely distributable copyrighted software”. That is, everyone is allowed to copy and use it, however the copyright remains with me. The program can also only be redistributed in an unaltered state.

The program can not be sold commercially without my explicit prior consent. Distributed as PD software, the price must not exceed 5 DM (=3 DM) per disk.

It can also only be redistributed in a complete and unaltered shape.

The sources may be altered, as long as this is stated clearly and the copyright notice remains unaltered in the source. When alterations have been made, I should be notified of these as much as possible, so that they can be built into the general version.

Note the copyright on the files ‘flext.c’ and ‘specialparse.c’.

For further explanation see the README file.

2. About SpecialHost

Anyone, who has worked a little with TEX, knows its greatest disadvantage: the missing possibility to produce graphs and include them in texts. There are hooks present though, to do this in TEX (via LaTEX or PICTEX) but these methods are doomed as soon as the graphs get just a little bit complicated.

You can bypass these limitations only with a trick: the use of the \special-command. Fortunately a possibility was envisioned in the DVI File Format, to incorporate nonstandardized things in the DVI file too. For this, the \special command is available. Everything that follows the command within accolades is taken up in the DVI file without changes. This way driver dependant commands can get past the TEX program into the DVI file. The particular driver can evaluate the \special-string and bind for example a graph into the current page.

The disadvantage of this method should not be kept secret though. As sson as you start working with \special-strings, the DVI file is not portable anymore. That means, that you cannot transfer this file to an arbitrary computer and expect, that the output there will be exactly the same, as on your own system. However, this limitation does not weigh that heavy altogether, since in the worst case the \special-strings are just ignored and the text is printed without graphics just the same anyway.

How does SpecialHostwork? SpecialHost uses the possibility of multitasking and message transfer of the AMIGA, to evaluate the \special-strings in the most flexible manner possible. SpecialHost is started parallel to the particular driver (ShowDVI or DVIprint) and waits for an incoming message of the driver. Should the driver encounter a \special-string when evaluating a DVI file, then it passes this unchanged to the SpecialHost- program together with some further information like the resolution of the picture at the time.

The task of the SpecialHost program is to get the message of the driver and to evaluate the \special-string. If the name of an IFF file is given in the string, the program loads the picture stipulated, and adjusts it to the selected resolution (reduces or enlarges it). After that, it passes the bitmap created on to the driver. This only has to copy it into its own bitmap, in which it keeps an entire TEXpage.

But why a private program for the evaluation of the \special-string? This solution is in my view considerably more flexible, as that of building a complete evaluation of the \special-string into every driver. Because a solidly defined interface between the drivers and the SpecialHost-program exists, the programs can be developed indepently from eachother, without encountering greater difficulties.

This way you can for example redefine the format of the \special-string or build new skills into the SpecialHost-program like that of evaluating of color- or vectorgraphics, without having to change even a bit in the drivers. Or in case I change something in the drivers and someone has written an own version of the SpecialHost-program, no trouble should arise, when these programs cooperate.

I publish the entire source of the SpecialHost-program, so that the advantage can be of some importance. Perhaps somebody, who knows his way around in graphic processing and is interested can extend the program.

3. Calling SpecialHost

At the present development stage SpecialHost has not got any option, which could be passed to it, when calling it.

The only particularity is maybe, that the program runs itself in the background automatically. The CLI-prompt appears immediately again after execution. The program also ignores ’stdin’ and ’stdout’, ’stderr’ is used for outputting a message in case of a more important error message. In such a situation the program ends itself.

4. SpecialHost’s window structure

The window of SpecialHost is divided into three parts. The upper part serves for input. There are all the gadgets, with which the program is directed.

The centre part only exists from a status line, in which it is displayed, in what manner the program should pass the pictures.

The lower part is meant as a control window for the activities of the program. There it is logged, what the program is doing at that particular moment. It also remembers the lines that are scrolled out at the top, when it displays a lot of messages. These can be retrieved with the cursor keys.

5. Operating SpecialHost

The program is managed completely by gadgets. These are: Memory When you click on this gadget, you order the SpecialHost program, to pass

a pointer of the bitmap of the picture to be included to the printerdriver or previewer.

6. The format of the \special-string 5

File This gadget makes, that the driver is passed only one filename, in which the bitmap is stored in a special (simple) format. The file ends on the resolution of the driver in DPI. At that however, first it is tested whether this file is younger as the actual IFF file. Is the IFF file newer – so it must have been changed – or the bitmap file does not yet exist, then the bitmap is created in memory and the bitmap file is freshly created. As the picture is then already in memory anyway, the bitmap is now passed directly.

Mem-B This gadget is related to the Memory gadget. The only difference is, that the

driver is additionally appointed to draw a border around the picture.

File-B This gadget resembles the File gadget, however, the driver draws a border

around the picture.

Border Here, the SpecialHost program points the driver, to actually draw a border, which corresponds to the size of the picture. The size is evaluated by the SpecialHostprogram, by reading the header of the IFF file.

Rect. Has the same function as the Border gadget. But now, not a border, but a

filled rectangle is shown.

Base DPI With this gadget you indicate, in which resolution the IFF pictures are drawn, which you include in the TEX-text. The default value is 100dpi. This means, that a picture in the previewer, set to 100dpi, is shown unchanged. In case of a printer driver with 300dpi resolution however, the picture is enlarged by a factor 3. When the Base DPI remains set to 100, it means, that 100 pixels in the IFF picture are always one inch on the page – all the same with which resolution this picture is displayed or printed out.

Icon By clicking this gadget the window is transformed into a small icon. You can reopen this icon with a double click. The program continues its work uninterrupted as an icon as well.

6. The format of the \special-string

As the TEXdriver ShowDVI and DVIprint ask SpecialHost for the picture to be included, they must know after what they should be asking. This is present in the TEXtext, the command is the \special-string. All of

\special{arbitrary text}

of the \special-command that is within the accolades, is ignored by the TEXprogram and passed to the driver unchanged. If ShowDVI or DVIprint encounters such a string now, then it is checked, whether a SpecialHost program is running in the background. Is this not the case, then the \special-command is simply ignored. If the SpecialHost program is present, then it receives the complete string per message.

Thus it is the SpecialHost program, which evaluates the special-string and determines the meaning of each and every word of the string. As this special-string is not standardized in any way, the format can change from driver to driver.

So the suggested format only matters for this collection of drivers and has not yet been finalized here either. In newer versions, new functions will probably be added. However, downward compatibility is stressed, so that you can switch to newer versions without difficulty.

The present format of the \special-string:

                         \special{com1 com2 com3}

The particular commands within the braces are separated from eachother by one or more spaces.

A command itself consists of a keyword and a value, so that a more precise study of the \special-string shows the following format:

                  \special{key1=val1 key2=val2 key3=val3}

Between the keyword (key) and the value (val) an equal sign must always be present.

As keywords, the following exist up to now:

ifffile defines the filename of an IFF-file,

hoffset indicates a horizontal offset,

voffset indicates a vertical offset,

hsize determines the horizontal size of the picture, vsize determines the vertical size of the picture,

At ifffile an IFF-file is given as the value of the filename. Plus, you should mind that the current directory is that one, from which the SpecialHostprogram has been started. Because of this, the filename of an IFF-file should always contain the entire path. In the present version it is unfortunately not yet possible, to change the current directory from within the SpecialHost program.

In case of the other four keywords, an indication of the dimension is expected as the value. This consists of a real number plus a calculation of the unit. The following units are available:

pt point (is used by TEX)

pc pica 1pc = 12pt

in inch 1in = 72.27pt

bp big point 72bp = 1in

cm centimeter

mm millimeter

dd didôt point 1157dd = 1238pt

cc cicero 1cc = 12dd

Here a few examples for a \special-string:

• \special{ifffile=dh0:pict/graphic1}

Here the IFF-file “graphic1” from the directory “dh0:pict” is included at the current text position.

• \special{ifffile=graphic2 hoffset=1.5in}

This time, the picture is taken from the current directory of the SpecialHost program and moved 1,5 inch to the right.

• \special{ifffile=graphic3 voffset=-1cm hsize=2in vsize=1in}

The picture “graphic3” is moved one centimeter upward in this example and enlarged or reduced to the size of 2 by 1 inch.

When using the keywords hsize and vsize by the way, you do not have to take the right selection of the “Base DPI” into consideration anymore, as then the picture in any case will be brought on the size necessary. The original size of the picture will then be ignored.

7. The software interface to the drivers

Here a short view into the working of the SpecialHost program.

7.1. The communication through ports

The communication of the driver with the SpecialHost program is taking place through a message port. As soon as SpecialHost is started, it opens a port with the name “special dvi”. The program waits by this port for messages of the driver.

When a driver encounters a \special-string in the DVI-file, it first tests, whether the port of the SpecialHost program exists. If not, it ignores the string. In case it does, the driver creates a port with the name “special reply” and installs it as a reply port.

Through the port “special dvi” it sends the SpecialHost program a message, in which the current resolution of the printer (or that of the screen) as well as the \special-string are contained.

SpecialHost evaluates this message and appends the special map structure to it. This contains the size of the picture, the offset and also the name of the bitmap file or a pointer to the bitmap. This message sends it per “ReplyMsg” back to the driver.

As soon as the driver has evaluated all the information of the “special map”, it sends the SpecialHost program another message, so that it knows, that the storage space of the “special map” can be freed again. This message is acknowledged by SpecialHost immediately.

After that the driver erases its Reply-Port.

While this communication is happening – between the sending of the first message by the driver, and the return of the second message by the SpecialHost program – the dialogue between the two partners must not be interrupted. As soon as one of the two terminates the communication, a deadlock is created. The other program waits until the next reset. As no timeout is implemented, in this case only a reboot helps. If you change the SpecialHost program, then you should take notice, that during the communication the program cannot be broken. Also in case of an error, the communication must be finished.

7.2. The bitmap-file format

In order to avoid the time consuming enlargement or reduction of the pictures, there is the possibility of storing the pictures that have been brought to the right size already. You can set this with the two File-gadgets.

In order to always have the pictures ready in the various resolutions, the corresponding resolution of the printer (respectively that of the screen) is appended when storing. If you store the picture testpic in the previewer with a resolution of 91dpi, a file testpic.91x91 is created.

This file has a very special format. The first four bytes of the file are the ‘Magic Word’ “SPEC”. You can see from this, that it is a bitmap file of the SpecialHost program.

The next four bytes appear, when you add up the special-string that belongs to this file, character for character. This is useful for recognizing whether the special-string has \underline{8. To Do 8} changed since you have created the file. Is this the case, then the picture is recomputed and stored.

Now two longwords follow, which indicate the width and the height of the picture in pixels.

Finally, the bitmap comes, line for line. The length of a line is rounded upwards to 16 bits. Thus, for a line with 100 bit, you need seven 16-bit words.

Another piece of data is stored with the file. The date of creation. It is used to check, whether the IFF picture is younger then the bitmap file. Is this the case, then of course the bitmap must be recomputed, as the IFF picture has apparently changed.

By this comparison of the dates and by the checking of the \special-string it is made sure, that no obsolete bitmap file is used. So you can use the drawing mode Transfer picture in a file as the standard, without trouble. This way, a picture for a resolution has to be computed only once, and is always available after that as a file. The only thing, that can become a problem, is the memory, as the bitmap files are not stored compressed.

7.3. The Source

In order to quickly learn your way around in the source, a short description of each file is given here. special.c Source of the communications-functions for the drivers. special.h Definitions of the structurs, which are used for the communication. flextr.c Module for enlargement or reduction of monochrome bitmaps. Algorithms

taken from the FBM-package

specialhost.c Module with all the funktions, which are used for the communication with

the drivers. Plus functions for the evaluation of the \special-string.

specialhost.h Defines for error messages and Draw-Mode. Plus prototypes of the module

’violating’ functions.

specialparse.c Module that takes over the evaluation of the \special-string. This module is originating from the file “dospecial.c” of the PostScript-driver “dvips” by Thomas Rokicki.

specialparse.h Definitions of the structurs for the file “specialparse.c”. specialwin.c In this module the window- and gadget-handling is being handled. Also

present here is the “main”-function with the main loop, in which there is waited for all possible signals.

specialwin.h The gadgets are defined here. iff.h Headerfile of Christian A. Weber’s “iff.library”. However, I have changed

it in a way, that the pragmas can now also be used with the Aztec-C compiler.

8. To Do

Apart from some minor flaws when operating the program, especially a better picture processing is missing.

For one, no colour pictures can be processed. On the other side, it would be certainly a great gain, if you could include vector-graphics.

But that is why I release the complete source to the program. Perhaps somebody who knows his way around in graphic-processing, has a little time and is willing to put some effort into it, will incorporate his knowledge in the program.

9. Hard- and software required

As far as hardware goes: an Amiga, and if possible with somewhat more memory. Otherwise, it could come to storage shortages in case of large pictures and high resolution.

As software, the TEX-drivers, ShowDVI and DVIprintare needed. Plus the “iff.library” by Christian A. Weber.

10. Known bugs

The file “specialwin.c” cannot be compiled with the optimizer of Lattice. On the other hand, the Aztec-C compiler Version 5.0a creates incorrect code for the module “specialparse.c”.

Translation from German to English by Thomas Tavoly.